github.com/hyperion-hyn/go-ethereum@v2.4.0+incompatible/docs/Privacy/Tessera/Tessera Services/Enclave.md (about)

     1  ## Enclave
     2  
     3  ### What is an enclave?
     4  
     5  An enclave is a secure processing environment that acts as a black box for processing commands and data. Enclaves come in various forms, some on hardware and others in software. In all scenarios, the purpose is to protect information that exists inside of the enclave from malicious attack.
     6  
     7  ### What does a Tessera enclave do?
     8  
     9  The Tessera enclave is designed to handle all of the encryption/decryption operations required by the Transaction Manager, as well as all forms of key management.
    10  
    11  This enables all sensitive operations to be handled in a single place, without any leakage into areas of program memory that don't need access. This also means that a smaller application can be run in a secure environment, where memory constraints are often more stringent, such as hardware enclaves.
    12  
    13  The Transaction Manager, which handles peer management and database access, as well as Quorum communication does not perform **any** encryption/decryption, greatly reducing the impact an attack can have.
    14  
    15  ### What exactly does the enclave handle?
    16  
    17  The Tessera enclave **handles** the following data:
    18  
    19  - public/private key access
    20  - public keys of extra recipients (** should be moved into Transaction Manager, not sensitive)
    21  - default identity of attached nodes
    22  
    23  The enclaves **performs** the following actions on request:
    24  
    25  - fetching the default identity for attached nodes (default public key)
    26  - providing forwarding keys for all transactions (** should be moved into Transaction Manager, not sensitive)
    27  - returning all public keys managed by this enclave
    28  - encrypting a payload for given sender and recipients
    29  - encrypting raw payloads for given sender
    30  - decrypting transactions for a given recipient (or sender)
    31  - adding new recipients for existing payloads
    32  
    33  ### Where does the Enclave sit in the private transaction flow?
    34  
    35  The Enclave is the innermost actor of the sequence of events. The below diagram demonstrates where the enclave sits:
    36  
    37  ![Quorum Tessera Privacy Flow](https://github.com/jpmorganchase/tessera/raw/master/Tessera%20Privacy%20flow.jpeg)
    38  
    39  As the diagram shows, each enclave interacts only with it's own transaction manager and no-one else.
    40  
    41  Tessera provides different types of Enclaves to suit different needs:
    42  
    43  ### Types of Enclave
    44  
    45  #### Local enclave
    46  The local enclave is the classical option that was included in versions of Tessera prior to v0.9. This includes the enclave inside the same process and the transaction manager. This is still an option, and requires all the enclave configuration to be inside the same configuration file and the Transaction Manager configuration.
    47  
    48  ##### How to use?
    49  In order to use the local enclave, you simply need to not specify an Enclave server type in the configuration. don't forget to specify the enclave config in the Transaction Manager config file.
    50  
    51  
    52  #### HTTP Enclave
    53  The HTTP Enclave is a remote enclave that serves RESTful endpoints over HTTP. This allows a clear separation of concerns for between the Enclave process and Transaction Manager (TM) process. The enclave must be present and running at TM startup as it will be called upon for initialisation.
    54  
    55  ##### How to use?
    56  The HTTP enclave can be started up by specifying an `ENCLAVE` server app type, with REST as the communication type. This same configuration should be put into the TM configuration so it knows where to find the remote enclave. Remember to set TLS settings as appropriate, with the TM being a client of the Enclave.
    57  
    58  ##### Advantage?
    59  The HTTP enclave could be deployed in a completely secure environment away from local machine where TM process runs and it adds this additional layer of security for private keys which is only accessible from HTTP enclave.
    60  
    61  
    62  ### Setting up an Enclave
    63  
    64  ### Configuration
    65  
    66  The configuration for the enclave is designed to the same as for the Transaction Manager.
    67  
    68  #### Local Enclave Setup
    69  The following should be present in the TM configuration:
    70  ```json
    71  {
    72      "keys": {
    73          "keyData": [{
    74              "privateKey": "yAWAJjwPqUtNVlqGjSrBmr1/iIkghuOh1803Yzx9jLM=",
    75              "publicKey": "/+UuD63zItL1EbjxkKUljMgG8Z1w0AJ8pNOR4iq2yQc="
    76          }]
    77      },
    78  
    79      "alwaysSendTo": []
    80  }
    81  ```
    82   
    83  #### Remote Enclave Setup
    84  The configuration required is minimal, and only requires the following from the main config (as an example):
    85  
    86  In the remote enclave config:
    87  ```json
    88  {
    89      "serverConfigs": [{
    90          "app": "ENCLAVE",
    91          "enabled": true,
    92          "serverAddress": "http://localhost:8080",
    93          "communicationType": "REST",
    94          "bindingAddress": "http://0.0.0.0:8080"
    95      }],
    96  
    97      "keys": {
    98          "keyData": [{
    99              "privateKey": "yAWAJjwPqUtNVlqGjSrBmr1/iIkghuOh1803Yzx9jLM=",
   100              "publicKey": "/+UuD63zItL1EbjxkKUljMgG8Z1w0AJ8pNOR4iq2yQc="
   101          }]
   102      },
   103  
   104      "alwaysSendTo": []
   105  }
   106  ```
   107  
   108  and in the TM configuration:
   109  ```json
   110  "serverConfigs": [{
   111      "app": "ENCLAVE",
   112      "enabled": true,
   113      "serverAddress": "http://localhost:8080",
   114      "communicationType": "REST"
   115  }],
   116  ```
   117  The keys are the same as the Transaction Manager configuration, and can use all the key types including vaults.  When using a vault with the enclave, be sure to include the corresponding jar on the classpath, either:
   118  
   119  * `/path/to/azure-key-vault-0.9-SNAPSHOT-all.jar`
   120  * `/path/to/hashicorp-key-vault-0.9-SNAPSHOT-all.jar`
   121  
   122  If using the all-in-one Transaction Manager jar, all the relevant files are included, and just the configuration needs to be updated for the TM.
   123  
   124  If using the individual "make-your-own" jars, you will need the "core Transaction Manager" jar along with the "Enclave clients" jar, and add them both to the classpath as such: `java -cp /path/to/transactionmanager.jar:/path/to/enclave-client.jar com.quroum.tessera.Launcher -configfile /path/to/config.json`